\chapter{Lap around \headset extension mechanisms}
In this chapter we describe the basic interface and how they fit in the general architecture of \headset. \headset contains three types of objects. The most important one for third-party developers is the instrument. An instrument is the representation of a physical instrument in the \headset environment. The second most important one is a geom. A geom can be either a safe path or a tumour. Both share the property that they are areas where the instrument is allowed to access. The final one is a DICOM model. A DICOM model is a representation of a MRI or CT scan in the \headset environment. The current APIs only provide support for listening to geom and instrument events, and only allow for third-party control of the instrument. But this may change in the future.

\section{Output}
\headset provides a large \verb|OutputController| that can be extend to listen to desired events. The \verb|OutputController| can listen to geoms and instruments. Events are provided in three levels, from quite coarse events to very detailed events. Listening coarsely might mean that you are just listening if something was updated in a geom. Listening to the most precise event might mean listening to the updates generated by changing the x-component of the position. 
A number of events are not related to geoms or the instrument. They give information if a user pressed for example the 'Start recording' button or the 'Stop recording' button. These buttons are currently only available in the recording application. But all other functionality can be used in the other \headset applications. 

\section{Input}
The system provides a collection of classes for providing input. Input can only be provided via an input Interface. This wraps \headset for usage. Just wrapping the model is not enough. \headset also provides an \verb|InputController| class that can be extended. This class has a number of more specialized subclasses that define some behaviour. An ordinary \verb|InputController| just allows \headset to start and stop a recording. While a \verb|PolledInputController| allows the \headset to poll the device with a user interface (this is currently not used). The most advanced \verb|InputController| is a \verb|TimedInputController|, which allows a device to be polled constantly. \headset is designed to operate as a single threaded system. This means that classes that derive from \verb|InputController| should not have long running loops. Also multithreaded \verb|InputContoller| classes are not tested, so their behaviour is not known. 

\section{The .hdt file format}
The file format used in headset can also be seen as a possible extension mechanism. Every .hdt file is in fact a compressed archive, implemented using the Python tarfile module.
Every archive might contain the following files:

\begin{enumerate*}
\item \verb|data.xml|, describing an overview of every primitive shape found in the model, in XML format.
\item If CT-scans are included in the file they are put in the \verb|dicom| folder.
\item Recordings are saved in the \verb|rec| folder, as comma-seperated-value files.
\end{enumerate*}
The \verb|ArchiveSaver| class offers functions for adding and reading al these elements. Removing elements is impossible for technical reason imposed by the tarfile module.
